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Extended Generic Security Service Mechanism Inquiry APIs 


Abstract 


This document introduces new application programming interfaces 

(APIs) to the Generic Security Services API (GSS-API) for extended 
mechanism attribute inquiry. These interfaces are primarily intended 
to reduce instances of hardcoding of mechanism identifiers in GSS 
applications. 


These interfaces include mechanism attributes and attribute sets, a 
function for inquiring the attributes of a mechanism, a function for 
indicating mechanisms that possess given attributes, and a function 
for displaying mechanism attributes. 


Status of This Memo 


This document specifies an Internet standards track protocol for the 
Internet community, and requests discussion and suggestions for 


improvements. Please refer to the current edition of the "Internet 
Official Protocol Standards" (STD 1) for the standardization state 
and status of this protocol. Distribution of this memo is unlimited. 


Copyright Notice 


Copyright (c) 2009 IETF Trust and the persons identified as the 
document authors. All rights reserved. 


This document is subject to BCP 78 and the IETF Trust’s Legal 
Provisions Relating to IETF Documents in effect on the date of 
publication of this document (http://trustee.ietf.org/license-info). 
Please review these documents carefully, as they describe your rights 
and restrictions with respect to this document. 
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1. Introduction 


GSS-API [RFC2743] mechanisms have a number of properties that may be 
of interest to applications. The lack of APIs for inquiring about 
available mechanisms' properties has meant that many GSS-API 
applications must hardcode mechanism Object Identifiers (OIDs). 
Ongoing work may result in a variety of new GSS-API mechanisms. 
Applications should not have to hardcode their OIDs. 


For example, the Secure Shell version 2 (SSHv2) protocol [RFC4251] 
supports the use of GSS-API mechanisms for authentication [RFC4462] 
but explicitly prohibits the use of Simple and Protected GSS-API 
Negotiation (SPNEGO) [RFC4178]. Future mechanisms that negotiate 
mechanisms would have to be forbidden as well, but there is no way to 
implement applications that inquire what mechanisms are available and 
then programmatically exclude mechanisms "like SPNEGO". 


2. Conventions Used in This Document 
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 


"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in [RFC2119]. 


Williams Standards Track [Page 2] 


RFC 5587 Extended GSS Mech Inquiry July 2009 


3. New GSS-API Interfaces 


We introduce a new concept -- that of mechanism attributes. By 
allowing applications to query the set of attributes associated with 
individual mechanisms and to find out which mechanisms support a 
given set of attributes, we allow applications to select mechanisms 
based on their attributes without having to hardcode mechanism OIDs. 


Section 3.1 describes the mechanism attributes concept. Sections 
3.4.2, 3.4.3, and 3.4.4 describe three new interfaces that deal in 
mechanisms and attribute sets: 


o GSS Indicate mechs by attrs() 
o GSS Inquire attrs for mech() 
o GSS Display mech attr() 
3.1. Mechanism Attributes and Attribute Sets 


An abstraction for the features provided by mechanisms and pseudo- 
mechanisms is needed in order to facilitate the programmatic 
selection of mechanisms.  Pseudo-mechanisms are mechanisms that make 
reference to other mechanisms in order to provide their services. 
For example, SPNEGO is a pseudo-mechanism, for without other 
mechanisms SPNEGO is useless. 


Two data types are needed: one for individual mechanism attributes 
and one for mechanism attribute sets. To simplify the mechanism 
attribute interfaces, we reuse the 'OID' and 'OID set' data types and 
model individual mechanism attribute types as OIDs. 


To this end, we define an open namespace of mechanism attributes and 
assign them arcs off of this OID: 


&123.051.5.5,.135 


Each mechanism has a set of mechanism attributes that it supports as 
described in its specification. 
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3.2. List of Known Mechanism Attributes 


+ ———————————————— S 


Williams 


Mech Attr Name 


GSS C MA MECH CONCRETE 
GSS C MA MECH PSEUDO 
GSS C MA MECH COMPOSITE 
GSS C MA MECH NEGO 

GSS C MA MECH GLUE 

GSS C MA NOT MECH 


GSS C MA | 


GSS C MA 


DEPRECATED 
NOT DFLT MECH 


. AUTH TARG 


AUTH INIT INIT 


AUTH TARG INIT 


AUTH INIT ANON 


AUTH TARG ANON 


DELEG CRED 


INTEG PROT 


. CONF PROT 


GSS C MA MIC 


GSS C MA OOS DET 
GSS C MA CBINDINGS 


GSS C MA CTX TRANS 
«reserved» 


T 
| 
+ 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
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Table 1 


Standards Track 


Arc Name 


concrete-mech 
pseudo-mech 
composite-mech 


mech-negotiation-mech 


mech-glue 
not-mech 
mech-deprecated 
mech-not-default 
initial-is-framed 
auth-init-princ 
auth-targ-princ 


auth-init-princ-initial 
auth-targ-princ-initial 


auth-init-princ-anon 
auth-targ-princ-anon 
deleg-cred 
integ-prot 

conf-prot 

mic 

wrap 

prot-ready 
replay-detection 
oos-detection 
channel-bindings 

pfs 

compress 
context-transfer 
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+-------------------- -- -- $4 = + 
| Mech Attr Name Purpose 
+------------------ 4 = + 


GSS C MA MECH CONCRETE 


GSS C MA MECH PSEUDO 


GSS C MA MECH COMPOSITE 


GSS C MA MECH NEGO 


GSS C MA MECH GLUE 


GSS C MA NOT MECH 


GSS C MA DEPRECATED 


GSS C MA NOT DFLT MECH 


GSS C MA ITOK FRAMED 


GSS C MA AUTH INIT 


GSS C MA AUTH TARG 


GSS C MA AUTH INIT INIT 


GSS C MA AUTH TARG INIT 


GSS C MA AUTH INIT ANON 
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Indicates that a mech is neither a 
pseudo-mechanism nor a composite 
mechanism. 

Indicates that a mech is a 
pseudo-mechanism. 

Indicates that a mech is a composite of 
other mechanisms. This is reserved for 
a specification of "stackable" 
pseudo-mechanisms. 

Indicates that a mech negotiates other 
mechs (e.g., SPNEGO has this 
attribute). 

Indicates that the OID is not for a 
mechanism but for the GSS-API itself. 
Indicates that the OID is known, yet it 
is also known not to be the OID of any 
GSS-API mechanism (or of the GSS-API 
itself). 

Indicates that a mech (or its OID) is 
deprecated and MUST NOT be used as a 
default mechanism. 

Indicates that a mech (or its OID) MUST 
NOT be used as a default mechanism. 
Indicates that the given mechanism's 
initial context tokens are properly 
framed as per Section 3.1 of [RFC2743]. 
Indicates support for authentication of 
initiator to acceptor. 

Indicates support for authentication of 
acceptor to initiator. 

Indicates support for "initial" 
authentication of initiator to 
acceptor. "Initial authentication" 
refers to the use of passwords, or keys 
stored on tokens, for authentication. 
Whether a mechanism supports initial 
authentication may depend on IETF 
consensus (see Security 
Considerations). 

Indicates support for initial 
authentication of acceptor to 
initiator. 

Indicates support for 

GSS C NT ANONYMOUS as an initiator 
principal name. 
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The Kerberos V mechanism [RFC1964] provides the following mechanism 


GSS C MA AUTH TARG ANON 


GSS C MA DELEG CRED 


GSS C MA INTEG PROT 


GSS C MA CONF PROT 


GSS C MA MIC 


GSS C MA WRAP 
GSS C MA PROT READY 


GSS C MA REPLAY DET 
GSS C MA OOS DET 


GSS C MA CBINDINGS 
GSS C MA PFS 


GSS C MA COMPRESS 


GSS C MA CTX TRANS 


+ Se Gri pali cra Pg. a eee es nog qui ali re c aes tema Sy i pal ey as spa MR pli 
3.3. Mechanism Attribute Sets 

attributes: 

o GSS C MA MECH CONCRETE 

o GSS C MA ITOK FRAMED 

o GSS C MA AUTH INIT 

o GSS C MA AUTH TARG 

o GSS C MA DELEG CRED 

o GSS C MA INTEG PROT 

o GSS C MA CONF PROT 
Williams St 
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Indicates support for 
GSS_C_NT_ANONYMOUS as a target 
principal name. 

Indicates support for credential 
delegation. 

Indicates support for per-message 
integrity protection. 

Indicates support for per-message 
confidentiality protection. 

Indicates support for Message Integrity 
Code (MIC) tokens. 

Indicates support for WRAP tokens. 
Indicates support for per-message 
protection prior to full context 
establishment. 

Indicates support for replay detection. 
Indicates support for out-of-sequence 
detection. 

Indicates support for channel bindings. 
Indicates support for Perfect Forward 
Security. 

Indicates support for compression of 
data inputs to GSS_Wrap(). 

Indicates support for security context 
export/import. 


Table 2 


of Existing Mechs 
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o GSS_C_MA MIC 

o GSS C MA WRAP 

o GSS C MA PROT READY 
o GSS C MA REPLAY DET 
o GSS C MA OOS DET 


o GSS C MA CBINDINGS 


o GSS C MA CTX TRANS (some implementations, using implementation- 
Specific exported context token formats) 


The Kerberos V mechanism also has a deprecated OID that has the same 
mechanism attributes as above as well as GSS C MA DEPRECATED. 


The mechanism attributes of the Simple Public-Key GSS-API Mechanism 
(SPKM) [RFC2025] family of mechanisms will be provided in a separate 
document, as SPKM is currently being reviewed for possibly 
significant changes due to problems in its specifications. 


The Low Infrastructure Public Key (LIPKEY) mechanism [RFC2847] offers 
the following attributes: 


o GSS C MA MECH CONCRETE 
o GSS C MA ITOK FRAMED 


o GSS C MA AUTH INIT INIT 


o GSS C MA AUTH TARG (from SPKM-3) 


o GSS C MA AUTH TARG ANON (from SPKM-3) 


o GSS C MA INTEG PROT 


o GSS C MA CONF PROT 


o GSS C MA REPLAY DET 


o GSS C MA OOS DET 


o GSS C MA CTX TRANS (some implementations, using implementation- 
Specific exported context token formats) 
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(LIPKEY should also provide GSS C MA CBINDINGS, but SPKM-3 
requires clarifications on this point.) 

The SPNEGO mechanism [RFC4178] provides the following attributes: 
o GSS C MA MECH NEGO 
o GSS CMA ITOK FRAMED 


All other mechanisms' attributes will be described elsewhere. 


3.4. New GSS-API Function Interfaces 


Several new interfaces are given by which, for example, GSS-API 
applications may determine what features are provided by a given 
mechanism and what mechanisms provide what features. 


These new interfaces are all OPTIONAL. 


Applications should use GSS Indicate mechs by attrs() instead of 
GSS Indicate mechs() wherever possible. 


Applications can use GSS Indicate mechs by attrs() to determine what, 
if any, mechanisms provide a given set of features. 


GSS Indicate mechs by attrs() can also be used to indicate (as in 
GSS Indicate mechs()) the set of available mechanisms of each type 
(concrete, mechanism negotiation pseudo-mechanism, etc.). 


3.4.1. Mechanism Attribute Criticality 


Mechanism attributes may be added at any time. Not only may 
attributes be added to the list of known mechanism attributes at any 
time, but the set of mechanism attributes supported by a mechanism 
can be changed at any time. 


For example, new attributes might be added to reflect whether a 
mechanism's initiator must contact an online infrastructure and/or 
whether the acceptor must do so. In this example, the Kerberos V 
mechanism would gain a new attribute even though the mechanism itself 
is not modified. 


Applications making use of attributes not defined herein would then 
have no way of knowing whether a GSS-API implementation and its 


mechanisms know about new mechanism attributes. To address this 
problem, GSS Indicate mechs by attrs() and 
GSS Inquire attrs for mech() support a notion of critical mechanism 


attributes. Applications can search for mechanisms that understand 
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mechanism attributes that are critical to the application, and the 
application may ask what mechanism attributes are understood by a 
given mechanism. 


3.4.2. GSS_Indicate_mechs_by_attrs() 


Inputs: 

o desired mech attrs SET OF OBJECT IDENTIFIER -- set of GSS_C_MA * 
OIDs that the mechanisms indicated in the mechs output parameter 
MUST offer. 

o except mech attrs SET OF OBJECT IDENTIFIER -- set of GSS C MA * 


OIDs that the mechanisms indicated in the mechs output parameter 
MUST NOT offer. 


o critical mech attrs SET OF OBJECT IDENTIFIER -- set of GSS C MA * 
OIDs that the mechanisms indicated in the mechs output parameter 
MUST understand (i.e., mechs must know whether critical attributes 
are or are not supported). 


Outputs: 

o major status INTEGER 

o minor status INTEGER 

o mechs SET OF OBJECT IDENTIFIER -- set of mechanisms that support 
the given desired mech attrs but not the except mech attrs, and 


all of which understand the given critical mech attrs (the caller 
must release this output with GSS Release oid set()). 


Return major status codes: 


o GSS S COMPLETE indicates success; the output mechs parameter MAY 
be the empty set (GSS C NO OID SET). 


o GSS S FAILURE indicates that the request failed for some other 
reason. 


GSS Indicate mechs by attrs() returns the set of OIDs corresponding 
to mechanisms that offer at least the desired mech attrs but none of 
the except mech attrs, and that understand all of the attributes 
listed in critical mech attrs. 


When all three sets of OID input parameters are the empty set, this 
function acts as a version of GSS indicate mechs() that outputs the 
set of all supported mechanisms. 
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3.4.3. GSS_Inquire_attrs_for_mech () 
Inputs: 


o mech OBJECT IDENTIFIER -- mechanism OID 


Outputs: 

o major status INTEGER 

o minor status INTEGER 

o mech attrs SET OF OBJECT IDENTIFIER -- set of mech attrs OIDs 


(GSS C MA *) supported by the mechanism (the caller must release 
this output with GSS Release oid set()). 


o known mech attrs SET OF OBJECT IDENTIFIER -- set of mech attrs 
OIDs known to the mechanism implementation (the caller must 
release this output with GSS Release oid set()). 


Return major status codes: 


o GSS S COMPLETE indicates success; the output mech attrs parameter 
MAY be the empty set (GSS C NO OID SET). 


o GSS S BAD MECH indicates that the mechanism named by the mech 
parameter does not exist or that the mech is GSS C NO OID and no 


default mechanism could be determined. 


o GSS S FAILURE indicates that the request failed for some other 
reason. 


GSS Inquire attrs for mech() indicates the set of mechanism 
attributes supported by a given mechanism. 


3.4.4. /.GSS Display mech attr() 


Inputs: 


o mech attr OBJECT IDENTIFIER -- mechanism attribute OID 
Outputs: 
o major status INTEGER 


o minor status INTEGER 
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o name OCTET STRING, -- name of mechanism attribute (e.g., 
GSS C MA *). 
o short desc OCTET STRING, -- a short description of the mechanism 


attribute (the caller must release this output with 
GSS Release buffer()). 


o long desc OCTET STRING -- a longer description of the mechanism 
attribute (the caller must release this output with 
GSS Release buffer()). 

Return major status codes: 

o GSS S COMPLETE indicates success. 

o GSS S BAD MECH ATTR indicates that the mechanism attribute 


referenced by the mech attr parameter is unknown to the 
implementation. 


o GSS S FAILURE indicates that the request failed for some other 
reason. 


This function can be used to obtain human-readable descriptions of 
GSS-API mechanism attributes. 


3.4.5. New Major Status Values 


A single, new, major status code is added for 
GSS Display mech attr(): 


o GSS S BAD MECH ATTR, 


roughly corresponding to GSS S BAD MECH but applicable to mechanism 
attribute OIDs rather than to mechanism OIDs. 


For the C-bindings of the GSS-API [RFC2744], GSS S BAD MECH ATTR 
shall have a routine error number of 19 (this is shifted to the left 
by GSS C ROUTINE ERROR OFFSET). 


3.4.6.  C-Bindings 


Note that there is a bug in the C bindings of the GSS-APIv2ul 
[RFC2744] in that the C 'const' attribute is applied to types that 
are pointer typedefs. This is a bug because it declares that the 
pointer argument is 'const' rather than that the object pointed by it 
is const. To avoid this error, we hereby define new typedefs, which 
include const properly: 
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typedef const gss_buffer_desc * gss_const_buffer_t; 
typedef const struct gss_channel_bindings_struct * 
gss_const_channel_bindings_t; 

typedef const <platform-specific> gss_const_ctx_id_t; 
typedef const <platform-specific> gss_const_cred_id_t; 
typedef const <platform-specific> gss const name t; 
typedef const gss OID desc * gss const OID; 

typedef const gss OID set desc * gss const OID set; 


Figure 1: const typedefs 


Note that only gss const OID and gss const OID set are used below. 
We include the other const typedefs for convenience since the C 
bindings of the GSS-API do use const with pointer typedefs when it 
should often instead use the above typedefs instead. 


#define GSS S BAD MECH ATTR (19ul << GSS C ROUTINE ERROR OFFSET) 


OM uint32 gss indicate mechs by attrs( 
OM uint32 *minor status, 
gss const OID set desired mech attrs, 
gss const OID set except mech attrs, 
gss const OID set critical mech attrs, 
gss OID set *mechs); 


OM uint32 gss inquire attrs for mech( 


OM uint32 *minor status, 

gss const OID mech, 

gss OID set *mech attrs, 

gss OID set *known mech attrs); 


OM uint32 gss display mech attr( 


OM uint32 *minor status, 
gss const OID mech attr, 
gss buffer t name, 

gss buffer t short desc, 
gss buffer t long deso); 


Figure 2: C bindings 


Note that output buffers must be released via gss release buffer(). 
Output OID sets must be released via gss release oid set(). 


Please see Appendix A for a full set of typedef fragments defined in 
this document and the necessary code license. 
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4. 


7. 


7. 


Requirements for Mechanism Designers 
All future GSS-API mechanism specifications MUST: 
o list the set of GSS-API mechanism attributes associated with them. 
IANA Considerations 
The namespace of programming-language symbols with names beginning 
with GSS C MA * is reserved for allocation by IETF Consensus.  IANA 
allocated a base OID, as an arc of 1.3.6.1.5.5, for the set of 


GSS C MA * described herein, and registered all of the GSS C MA * 
values described in Section 3.2. 


Security Considerations 


This document specifies extensions to a security-related API. It 
imposes new requirements on future GSS-API mechanisms, and the 
Specifications of future protocols that use the GSS-API should make 
reference to this document where applicable. The ability to inquire 
about specific properties of mechanisms should improve security. 


The semantics of each mechanism attribute may include a security 
component. 


Application developers must understand that mechanism attributes may 


be added at any time -- both to the set of known mechanism attributes 
as well as to existing mechanisms' sets of supported mechanism 
attributes. Therefore, application developers using the APIs 


described herein must understand what mechanism attributes their 
applications depend critically on, and must use the mechanism 
attribute criticality features of these APIs. 
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Appendix A.  Typedefs and C Bindings 


This appendix contains the full set of code fragments defined in this 
document. 


Copyright (c) 2009 IETF Trust and the persons identified as authors 
of the code. All rights reserved. 


Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met: 


- Redistributions of source code must retain the above copyright 
notice, this list of conditions and the following disclaimer. 


- Redistributions in binary form must reproduce the above copyright 
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the 
distribution. 


- Neither the name of Internet Society, IETF or IETF Trust, nor the 
names of specific contributors, may be used to endorse or promote 
products derived from this software without specific prior written 
permission. 


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 


typedef const gss buffer desc * gss const buffer t; 
typedef const struct gss channel bindings struct * 
gss const channel bindings t; 

typedef const <platform-specific> gss const ctx id t; 
typedef const <platform-specific> gss const cred id t; 
typedef const <platform-specific> gss const name t; 
typedef const gss OID desc * gss const OID; 

typedef const gss OID set desc * gss const OID set; 
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#define GSS S BAD MECH ATTR (19ul << GSS C ROUTINE ERROR OFFSET) 


OM uint32 gss indicate mechs by attrs( 


OM uint32 


gss const OID set 
gss const OID set 
gss const OID set 


gss OID set 


*minor status, 
desired mech attrs, 
except mech attrs, 
critical mech attrs, 

*mechs); 


OM uint32 gss inquire attrs for mech( 


OM uint32 

gss const OID 
gss OID set 
gss OID set 


*minor status, 
mech, 

*mech attrs, 
*known mech attrs); 


OM uint32 gss display mech attr( 


OM uint32 

gss const OID 
gss buffer t 

gss buffer t 

gss buffer t 


Author's Address 


Nicolas Williams 
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US 


*minor status, 
mech attr, 
name, 
short desc, 
long deso); 
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